---
sidebar_label: user-lockout
description: |-
  The user_lockout stanza specifies various configurations for user lockout behaviour for
  failed logins in OpenBao. 
---
# User lockout

If a user provides bad credentials several times in quick succession,
OpenBao will stop trying to validate their credentials for a while, instead returning immediately
with a permission denied error. We call this behavior "user lockout". The time for which
a user will be locked out is called “lockout duration”. The user will be able to login after the lockout
duration has passed. The number of failed login attempts after which the user is locked out is called
“lockout threshold”. The lockout threshold counter is reset to zero after a few minutes without login attempts,
or upon a successful login attempt. The duration after which the counter will be reset to zero
after no login attempts is called "lockout counter reset". This can defeat both automated and targeted requests
i.e, user-based password guessing attacks as well as automated attacks.

The user lockout feature is enabled by default. The default values for "lockout threshold" is 5 attempts,
"lockout duration" is 15 minutes, "lockout counter reset" is 15 minutes.

The user lockout feature can be disabled as follows:
- It can be disabled globally using environment variable `VAULT_DISABLE_USER_LOCKOUT`.
- It can be disabled for all supported auth methods (ldap, userpass and approle) or a specific supported auth method using the `disable_lockout`
  parameter within `user_lockout` stanza in configuration file.
  Please see [user lockout configuration](/docs/configuration/user-lockout#user_lockout-stanza) for more details.
- It can be disabled for a specific auth mount using "auth tune". Please see [auth tune command](/docs/commands/auth/tune)
  or [auth tune api](/api-docs/system/auth#tune-auth-method) for more details.

:::warning

**NOTE**: This feature is only supported by the userpass, ldap, and approle auth methods.

:::

## `user_lockout` stanza

The `user_lockout` stanza specifies various configurations for user lockout 
behaviour for failed logins in OpenBao. They can be configured for all supported auth methods
(userpass, ldap and approle) using "all" user_lockout stanza name or for a specific auth method 
using the auth method name in stanza. 

Supported user_lockout stanza names are all, userpass, ldap and approle.

The configurations for a specific auth method takes precedence over the configurations specified 
for all auth methods using "all" user_lockout stanza name in the config file.

## Configuration

User lockouts configuration is done through the OpenBao configuration file using
the `user_lockout` stanza:

```hcl
user_lockout [NAME] {
  [PARAMETERS...]
}
```

For example:

```hcl
user_lockout "all" {
  lockout_duration = "10m"
  lockout_counter_reset = "10m"
}

user_lockout "userpass" {
  lockout_threshold = "25"
  lockout_duration = "5m"
}

user_lockout "ldap" {
 disable_lockout = "true"
}
```

Here, user lockout feature will be disabled for ldap auth methods. Userpass auth methods will have lockout threshold of 25, 
lockout duration of 5 minutes, lockout counter reset of 10 minutes. Approle auth methods will have a lockout threshold of 
5 (considers default as this value is not configured), lockout duration of 10 minutes and lockout counter reset of 10 minutes.

The user lockout configuration for the auth method at a given path can be tuned using auth tune. Please see [auth tune command](/docs/commands/auth/tune)
or [auth tune api](/api-docs/system/auth#tune-auth-method) for more details. 

## `user_lockout` parameters

The following options are available on all user_lockout configurations.

- `lockout_threshold` `(string: "")` - Specifies the number of failed login attempts after which the user is locked out.
- `lockout_duration` `(string: "")` - Specifies the duration for which an user will be locked out.
- `lockout_counter_reset` `(string: "")` - Specifies the duration after which the lockout counter is reset with no failed login attempts.
- `disable_lockout` `(bool: false)` - Disables the user lockout feature if set to true.
